Form Validation with ARIA Live Regions

In this lesson, we’ll work with the form on the “Submit Your Spot” page of CampSpots. It can be navigated to from the “Resources” section of the MegaNav.

The form includes inputs, a custom checkbox, and a text area.

As it stands right now, if we submitted the empty form there’s nothing in place that would prevent the page from refreshing. There’s also no error handling or form validation yet.

In this lesson we’ll work on adding a live region as part of an implementation for form validation.

While HTML does offer some native validation, it isn’t super reliable on its own. Rolling our own custom validation is still what I recommend. This also allows us to take a hybrid approach and use a combination of announcements and focus management to alert the user about an invalid form state.

The code for the page can be found in components/page-submit-listing.js. There’s not much more than the markup in that file for the time being, but at least the form inputs are labeled!

The goal for the end of this section is to have the screen reader announce that there are invalid fields without moving the user’s focus.

Adding a Live Region to the Form

At line 24 inside of the <form> tag but outside of the layout divs, add a paragraph tag.

We will add the role attribute with a value of "alert" and set the aria-relevant attribute to "all". We’ll also add a CSS className of "error" so we can style this as an error message.

Here’s what the code looks like so far:

<form>
	<p className="error" role="alert" aria-relevant="all"></p>
	...

<form>
	<p className="error" role="alert" aria-relevant="all"></p>
	...

We’ve just created our first live region, ready to receive messages!

The p tag will be present when the page loads with a role and aria-relevant.

We’ll set it up so that it conditionally displays information. There are a couple things that need added to the form before we can do this.

Update the form to have an action

Our form currently doesn’t have an action associated with it.

We’ll add one and let it be an empty string since client-side JavaScript will be taking care of the form validation and submission to start.

We also add an onSubmit attribute that will pass an event object into a function called submitHandler that we’ll write near the top of the file outside of the return statement.

Here’s what our form tag looks like now:

<form
  action=""
  aria-describedby="key"
  onSubmit={event => submitHandler(event)}
>

<form
  action=""
  aria-describedby="key"
  onSubmit={event => submitHandler(event)}
>

Track variables in Component State

Before we write the submitHandler we need to set up some state variables for the component to track.

We need to know if the form has been submitted as well as if the form is dirty (fields have been edited but not yet submitted). We also need to keep track of whether there should be an error announcement or not.

At the top of the file where React is imported, we’ll also bring in the useState hook (and useRef for later).

import React, {useState, useRef} from "react"

import React, {useState, useRef} from "react"

Following React’s useState pattern, we’ll add our state variables and setter functions with initial boolean values of false:

// Above the `return()` in the component
let [isFormSubmitted, setIsFormSubmitted] = useState(false)
let [isFormDirty, setIsFormDirty] = useState(false)
let [errorAnnouncement, setErrorAnnouncement] = useState(false)

// Above the `return()` in the component
let [isFormSubmitted, setIsFormSubmitted] = useState(false)
let [isFormDirty, setIsFormDirty] = useState(false)
let [errorAnnouncement, setErrorAnnouncement] = useState(false)

Adding Default State for the Form

We’ll also track formState for the component and initialize the value to an object with default values for all of our form fields:

const [formState, setFormState] = useState({
  'sitename': '',
  'location': '',
  'fee': 0,
  'legalToCamp': true,
  'submittername': '',
  'email': '',
  'notes': ''
})

const [formState, setFormState] = useState({
  'sitename': '',
  'location': '',
  'fee': 0,
  'legalToCamp': true,
  'submittername': '',
  'email': '',
  'notes': ''
})

Writing the submitHandler function

Our submitHandler function will take in the event object.

The first thing we need to do inside the function is call event.preventDefault() since we don’t want the form to submit and refresh the page.

Then we’ll write some logic that will respond and manage any changes to the form state variables we tracked before.

When the form is submitted, we’ll call setIsFormSubmitted and pass in a true value.

setIsFormSubmitted(true)

setIsFormSubmitted(true)

We’ll also call setErrorAnnouncement and pass in a message about the required fields that will render inside our live region later on.

Here’s what it looks like so far:

const submitHandler = (event) => {
	event.preventDefault()
	setFormIsSubmitted(true)
	
	setErrorAnnouncement('Required fields cannot be empty.')
}

const submitHandler = (event) => {
	event.preventDefault()
	setFormIsSubmitted(true)
	
	setErrorAnnouncement('Required fields cannot be empty.')
}

Checking Progress in the Browser

With the live region element added to the form, we're at a good point to check our progress in the browser.

Since the <p> tag is empty, we'll use DevTools to add text content of "Error!" inside to preview what a message looks like.

Adding a Global Error Announcement in the Live Region

Inside of the submitHandler function, we have already called setErrorAnnouncement and passed in a global error message about required fields.

We still need to wire it up in our live region.

Inside the <p> tag we added earlier, we’ll use React and JSX to render the dynamic errorAnnouncement:

<p className="error" role="alert" aria-relevant="all">
{errorAnnouncement}
</p>

<p className="error" role="alert" aria-relevant="all">
{errorAnnouncement}
</p>

When setErrorAnnouncement has been called with a string message, it will automatically print inside of our live region and kick off an announcement in a screen reader.

Back in Safari, open up VoiceOver with Fn + CMD + F5.

While VoiceOver is reading the page, submit the form and it will immediately switch to reading our error message while retaining focus on the element. We’ve successfully added our first dynamic live region!

Since we know that the global error functionality is working, let's move on to adding individual error messages for each of the inputs.

Adding onChange Handlers to the Inputs

For each of the inputs in the form, we'll add an onChange event inline and bind it to a function called changeHandler that we will write in a moment.

Even though we have various types of inputs including text fields and a checkbox, we can reuse the same changeHandler function.

Above the return() of the component, create the changeHandler function that will take in the event object.

Inside of this function, we first need to get ahold of the target element from the event object. Then we'll check its value to see if it came from the checkbox or a text input.

We'll also grab the id attribute from the event.target.

Here's what the changeHandler looks like so far:

const changeHandler(event) => {
  const target = event.target
  const value = target.type === 'checkbox' ? : target.checked : target.value
  const id = target.id
}

const changeHandler(event) => {
  const target = event.target
  const value = target.type === 'checkbox' ? : target.checked : target.value
  const id = target.id
}

Now we'll call setIsFormDirty and set it to true since we know the form was edited as the change event has been called on at least one of the controls.

Updating State on Form Changes

Because each individual input can be updated, we need to compare the previous form state to its new value as the form onChange is called.

The spread operator (...) will help us set the new form state by merging its previous values with the updated value for an element with a given id.

This is a convenient way to essentially copy an object and overwrite only the part we need to.

setFormState(prevState => {
  return {...prevState, ...{
    [id]: value
  }}
})

setFormState(prevState => {
  return {...prevState, ...{
    [id]: value
  }}
})

All together, here's what the changeHandler function looks like:

const changeHandler(event) => {
  const target = event.target
  const value = target.type === 'checkbox' ? : target.checked : target.value
  const id = target.id

  setFormIsDirty(true)
  setFormState(prevState => {
    return {...prevState, ...{
      [id]: value
    }}
  })
}

const changeHandler(event) => {
  const target = event.target
  const value = target.type === 'checkbox' ? : target.checked : target.value
  const id = target.id

  setFormIsDirty(true)
  setFormState(prevState => {
    return {...prevState, ...{
      [id]: value
    }}
  })
}

Form Markup Updates

There are a few more things we can add to the form.

Conditional CSS Styling

We can add styling to the form depending on if isFormDirty is true or not, using a ternary operator and React className string:

<form
  action=""
  className={!isFormDirty ? `dirty` : ``}
  onSubmit={(event) => {submitHandler(event)}}
>

<form
  action=""
  className={!isFormDirty ? `dirty` : ``}
  onSubmit={(event) => {submitHandler(event)}}
>

Add aria-invalid to Individual Fields

The aria-invalid attribute is a great way to inform a person using a screen reader that there's something wrong with a form field.

Starting with the first input for the submitter's name, we'll add aria-invalid and compute its value with an expression that checks if the form was submitted and if the field is empty.

If the expression is true, the attribute will be added with a true value. Otherwise, we'll set the attribute value to null so it won't be added:

// On the Name input
<input
  aria-invalid={
    isFormSubmitted &&
    formState.submittername.length === 0 ? 'true' : null
  }
  onChange={changeHandler}
  type="text"
  id="submittername"
>

// On the Name input
<input
  aria-invalid={
    isFormSubmitted &&
    formState.submittername.length === 0 ? 'true' : null
  }
  onChange={changeHandler}
  type="text"
  id="submittername"
>

Checking Progress in the Browser

Back in the browser, hit the submit button on the empty form.

Red outlines will show up for the form fields that are invalid thanks to the CSS that we already had defined for when aria-invalid is true.

Styling based on ARIA attributes is a useful technique that works great for forms.

There are still some design questions that can arise. For example, an invalid form field should be focusable. But when focus shifts to it, the border of the input is now blue instead of red. Should it stay red? For how long? Maybe that's not important, since if I focused on a field I'm probably about to type in it. Another subjective situation.

The important thing here is that we are able to not only visually represent the form's validity, but programmatically for Assistive Technology as well.

🛠 Challenge: Send Focus to the First Invalid Field

At this point in development, when the user submits the form the live region will update with an error message but leave focus where it was.

It would be cool if after submitting, focus was sent directly to the first field with invalid input.

For this challenge, draw upon what you’ve learned about focus management and make it happen!

🛠 Solution: Sending Focus to the First Invalid Field

Step 1: Track Input Refs

The first thing we need to do is initialize our inputRefs at the top of the component near where we set up our state. Like with our date buttons before, we'll set it to useRef([]).

const inputRefs = useRef([]);

const inputRefs = useRef([]);

Now we need to add refs to the array dynamically for each of the text inputs.

Here's what the Name input looks like:

<input
  aria-invalid={
    isFormSubmitted && formState.submittername.length === 0 ? "true" : null
  }
  id="submittername"
  onChange={changeHandler}
  ref={(inputRef) => {
    inputRefs.current.push(inputRef);
  }}
  type="text"
/>

<input
  aria-invalid={
    isFormSubmitted && formState.submittername.length === 0 ? "true" : null
  }
  id="submittername"
  onChange={changeHandler}
  ref={(inputRef) => {
    inputRefs.current.push(inputRef);
  }}
  type="text"
/>

The process to add a ref will be the same for each of the inputs so feel free to do some copying and pasting.

It is worth pointing out that on further reflection I decided that neither the ownership checkbox nor the fee input should become invalid since a site might be free. Another example of how the use of the application can affect the coding decisions we make!

Step 2: Update the Submit Handler

Up inside of the submitHandler, we need to keep track of the elements in our form so we can grab the first empty one.

Create a new variable for firstEmptyElementIndex. We'll use the JavaScript let keyword so we can set the variable’s initial value to null and overwrite if we do find an empty element.

Then we will create an array of formElements by calling Array.from(event.target.elements).

Now we can iterate over the form elements, using a switch statement that looks at the elements’ type.

If it's the submit button, we'll return and break out of the switch.

For the default case for the switch statement, we will set isFormDirty to false since it's been submitted on the client-side. Then we'll add the logic that looks for empty form fields.

If we encounter an empty field and the firstEmptyElementIndex is null, we know we we've found our first empty element so we should set it to the current index. Then we can call inputRefs.current[index].focus() to send focus to it.

The call to setErrorAnnouncement will close out the default case of the switch statement.

Here's what the updated submitHandler looks like:

const submitHandler = (event) => {
  event.preventDefault();

  setIsFormSubmitted(true);

  let firstEmptyElementIndex = null;
  const formElements = Array.from(event.target.elements);
  formElements.map((element, index) => {
    switch (element.type) {
      // ignore the submit button
      case "submit":
        return;
        break;

      default:
        // set form state for aria-invalid
        setIsFormDirty(false);

        if (element.value.trim().length === 0) {
          // focus on first empty input when submitted
          if (firstEmptyElementIndex === null) {
            firstEmptyElementIndex = index;
            inputRefs.current[index].focus();
          }
          setErrorAnnouncement("Required fields cannot be empty.");
        }
        break;
    }
  });
};

const submitHandler = (event) => {
  event.preventDefault();

  setIsFormSubmitted(true);

  let firstEmptyElementIndex = null;
  const formElements = Array.from(event.target.elements);
  formElements.map((element, index) => {
    switch (element.type) {
      // ignore the submit button
      case "submit":
        return;
        break;

      default:
        // set form state for aria-invalid
        setIsFormDirty(false);

        if (element.value.trim().length === 0) {
          // focus on first empty input when submitted
          if (firstEmptyElementIndex === null) {
            firstEmptyElementIndex = index;
            inputRefs.current[index].focus();
          }
          setErrorAnnouncement("Required fields cannot be empty.");
        }
        break;
    }
  });
};

Checking Focus Management & VoiceOver

Back in the browser, we can can confirm that our focus is jumped to the first invalid field after we try to submit the form, just like we expected!

When we test the form with VoiceOver in Safari, we also get the behavior we expect.

However, from the announcement there's another opportunity for making the experience better.

The "invalid data" message could be customized based on the form field it came from. Or going further, what if the error was a network error? The data might be valid but the form couldn't submit. Something else to think about.

Adding aria-required to Required Form Fields

To experiment with ARIA vs. native HTML form validation, we are going to add the aria-required attribute and set it to true for each of the form fields that have been visually marked as required:

<input
  aria-invalid={...}
  aria-required="true"
  ...

<input
  aria-invalid={...}
  aria-required="true"
  ...

Saving our work and jumping back to the browser, we’ll start VoiceOver again.

VoiceOver does announce that a field is required but it also says the word “star” along with the label.

Announcement Considerations

Here’s the markup for the location label. Note that htmlFor in React/JSX renders as for in the browser to pair a label with an input.

<input
  aria-invalid={...}
  aria-required="true"
  ...

<input
  aria-invalid={...}
  aria-required="true"
  ...

It doesn't seem that the screen reader does anything with the abbr attribute for an accessible name, because it isn't a valid attribute in this context. (abbr can only be used on table headers, in fact.)

We could tell it to ignore the asterisk by setting aria-hidden="true" on the span, which would be fine since a screen reader user would still be informed that the field was required. But also, I subjectively wonder if "star" could be considered helpful content. It’s not the same situation as VoiceOver reading out a decorative “right-angled bracket” or “accent circumflex”, for example. Another option would include trying the <abbr> element with a title attribute explaining what the asterisk stands for.

This is another situation where your team could decide what to do based on feedback from daily screen reader users.

The important part is that you aren’t relying only on the user having to know that “star” means “required” when the Screen Reader announces it.

Checking Our Work in NVDA on Windows

We’ve seen how VoiceOver reads our page. Now we’ll check it with NVDA on Windows.

Before we do, let’s replace the live region’s role from alert to status to compare the behavior:

<p aria-relevant="all" className="error" role="status">

<p aria-relevant="all" className="error" role="status">

The status role will wait for other screen reader messages to complete before making an announcement, rather than interrupting and squashing other output. Check out the video below to listen to how NVDA makes announcements.

Section Wrap-Up

As you move forward with announcements, remember that the element with a live region role or aria-live attribute has to be rendered to the page at load time. Then, text content can be added to it on demand and read out.

If you try to append the actual live region itself just-in-time for the announcement, it’s probably too late.

We did a bunch of stuff in this section. Use the code here in your own experiments with ARIA attributes, form validation, custom error messages, or anything else to further your understanding and skills. And remember to test these techniques with Assistive Technology and the keyboard!